The first thing that you may wish to do is to create a folder in which to store your template files. I would suggest that you create this in your BBEdit folder (but anywhere will do). Enclosed with this archive is a folder called 'Templates'. You can either just drag this straight to where you want your templates to live, or copy the files enclosed into a folder you create yourself.
Now that we have a folder to hold our templates, we need to set the template file in the Preferences. Do this going to the 'Utilities' menu item, and selecting the 'Preferences' item. Select 'Template' from the popup menu, and then click on the button. This will then ask you to locate the template file - so do just that. (More information about setting your preferences is in the document 'Preferences_Docs.html')
This sets your default template, for use when you use the Document->Create tool. (Any other valid documents within the same folder can be quickly selected via the popup menu in the Create tool.)
Now that you have set the template file, to create a document using that template, select the 'Document->Create' tool. You will then have a window with a number of fields that you may or may not wish to fill in. You really must fill in the TITLE field, and I would strongly recommend that you fill in the BASE field as well.
In the bottom left corner is a popup menu that shows you which template file is currently selected for use with your settings. Select the template you wish to use (or just use the default setting). If you have used the default template that came with this archive, then you should see some of the information that you filled into the fields appear in the newly created document, based on the template file. This is done with 'placeholders'.
You can include certain placeholders in your template file. These are strings that will be replaced by some appropriate text. For example, you may wish to add the current date, or user-name to the file, and this can easily be done using placeholders.
Note: If you used earlier versions of the tools, you should be aware that I have changed the placeholder names. All placeholders starting #THE...# have had the 'THE' removed, as it was getting far too messy. So you will have to update your docs appropriately. Also note that the #NEXTID# placeholder has been removed, and is replaced by #META#.
You can enter a placeholder using the Document->MetaTags tool. Some of the tags are listed below...
Placeholder Action
=========== ======
#TITLE# the title of the document, as entered using the
Document tool.
#LINK# The link as entered using the Document tool.
#BASE# The base as entered using the Document tool.
#META# Any META attributes you may have entered.
#USERNAME# The user name (from chooser/sharing)
#MACHINE# The machine name.
#SHORTDATE# 29/10/95
#LONGDATE# Sunday, October 29, 1995
#ABBREVDATE# Sun, Oct 29, 1995
#COMPDATE# 29-Oct-95 (Useful compact and unambiguous format)
#TIME# The time
#ROOT# The root directory on your machine
#SERVER# The URL of your server.
#PATH# The path to access your documents from the server.
#BODYTEXT# A placeholder in a template where text currently in
your document should be placed.
#DONT_UPDATE# Will mark the file so that it won't be updated.
#REAL_URL# Will enter the real URL for the current document in
its current location.
#BASE_URL# the value of the BASE URL specified in the document.
(Useful if you want to refer to the document's
location)
Those of you who have used C and other programming languages will be familiar with include files. These are other files that can be included in the current file by using a reference to it (eg #include "test.html") Your HTML documents can therefore include other files, such as a header or footer file.
The way the standard include file reference is processed is that the file will replace the reference to it. So if your template contains a reference to a footer, then you write...
#include "footer.html"
When this template is used, this reference will be overwritten by the contents of the file it refers to.
Now there will be some of you who will be disappointed by this. Surely if the #include statement is overwritten, then it won't be possible to update the document if you ever decide you want to change the contents of the footer.
So what you really want is a way of ensuring that there is a reference to a file that stays in your document permanently. This raises the problem of how to have these file references in the document without fouling up the HTML for the user. My solution is to embed the include statement in an HTML comment. This way the user never sees it, but the reference remains in the document. The syntax is...
<!-- #include "footer.html" --> <!-- end include -->
Note that there is a closing comment. This is necessary because when the document is updated it needs to know which area of text can be replaced by the included file. (In the event of the file not being found, a message to that effect will be inserted).
If you do make any changes to your include files, you can update individual documents or your entire web by using the Document->Update tool.
Now, these include files should be stored in the same folder as your template file, so that the tools can find them easily. You can create subfolders in the template folder if you wish, as long as you change the file reference accordingly, eg
#include ":Footers:myFooter.html"
(note the colons, not slashes). You can also use aliases in your template folder if you wish to locate your documents elsewhere.
(new in version 2) Include files on their own are useful, but to be truly flexible there are occasions when it is necessary to add information to an include file on a document by document basis. As an example, you may have a standard format for your headers and footers, but may wish to change an image, or links as appropriate for each document. In this instance, you can set up some variables to be used within your include files. The short example below should show you how to use them...
Document:<!-- #include "footer.incl" #MY_GRAPHIC#="test1.gif" #MY_ALT_DESC#="a test image" #MY_TITLE#="Testing 1..2..3.." --> <!-- end include --> ...Include File "footer.incl":
...
<HR> <IMG SRC="#MY_GRAPHIC#" ALT="#MY_ALT_DESC#"> <HR> <H1>#MY_TITLE#</H1> ...
Variables are particularly useful for assisting with the construction of
navigation tools (be they text or graphic based). A very simplified version
might be...
Document:
...
<!-- #include "navBar.incl" #FORWARD#="./nextDoc.html" #BACKWARD#="./prevDoc.html" --> <!-- end include --> ...
Include File "navBar.incl":
...
<HR> <A HREF="#BACK#">Previous</A> | <A HREF="#FORWARD#">Next</A> <HR> ...
The variable name can be anything you want (max 32 characters), and must be delimited by hashes. The value of your variable must be bounded by quotes. If you need quotes within your variable, then escape them in the standard way (\"). Your variables must live within the include file comment.
Included files can themselves contain include files, so you can nest them to your heart's content. This also means that you could set up a recursive loop (ie file A includes file B which includes file A ad infinitum). This is a daft thing to do, but if you did, you can always use Command-. to escape out of the loop.
One thing to be aware of is that if you have an include file open in BBEdit, and it is used to update a file, it will appear to become corrupted. Don't worry, it hasn't. The answer is to not have any included files open when you are doing any updating. I don't know why it does this, but hope to sort it out by the next version.
Enjoy -
Lindsay